home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 11 / Cream of the Crop 11-1.iso / program / swmp141.zip / ASM.DOC < prev    next >
Text File  |  1995-12-12  |  8KB  |  162 lines
  1.  
  2.  ┌────────────────────────────────────────────────────────────────────────────┐
  3.  │ Module Player V1.41     (c) 1994,1995 by Lord Excess of Sound Wizards Int. │
  4.  └────────────────────────────────────────────────────────────────────────────┘
  5.  
  6.  
  7.  
  8.         USING THE SWMP DRIVERS WITH TURBO ASSEMBLER
  9.         ───────────────────────────────────────────
  10.         (or any other language allowing inline asm instructions)
  11.  
  12.  
  13.          First you have to unzip the files of archive ASM_SDK.ZIP.
  14.         Files you need in any case are:
  15.  
  16.           SB.DRV       : SoundBlaster driver      [ 22.2 kHz mono     ]
  17.           SBP.DRV      : SoundBlaster Pro driver  [ 21.7 kHz stereo   ]
  18.           GUS.DRV      : Gravis UltraSound driver [ 44.1 kHz +stereo+ ]
  19.           MODPLAY.LIB  : TASM library that holds all drivers
  20.           MODPLAY.INC  : include file for ModPlay.Lib
  21.  
  22.          The rest are example files, which can be important to
  23.         understand things better.
  24.  
  25.  
  26.          In general you first have to allocate memory and then load one
  27.         of the drivers into RAM (must be a paragraph address). So you
  28.         perhaps will be asking at program start which driver to load.
  29.         After having loaded the selected file, you can use the driver
  30.         by doing far calls to its first address (driver_segment:0000).
  31.  
  32.          Note: Memory allocation must be available via int 21h,
  33.         subfunction 48h. Therefore you have to adjust your own memory
  34.         control block first, else the drivers cannot alloc mem for the
  35.         soundfiles!
  36.  
  37.          Convention is that the register BX contains the subfunction
  38.         number, additional parameters are placed in AX,CX,DX etc.
  39.         The following subfunctions are available:
  40.  
  41.  
  42. ┌──INIT DRIVER─────────────────────────────────────────────────────────────────
  43. │       BX=0, CX,DX=configuration
  44. │           Initialize driver using configuration in CX and DX.
  45. │           Configuration for -SoundBlaster:      CL=IRQ NUMBER, CH=1
  46. │                                                 DX=BASE ADDRESS
  47. │                             -SoundBlaster Pro:  CL=IRQ NUMBER, CH=DMA CHANNEL
  48. │                                                 DX=BASE ADDRESS
  49. │                             -Gravis UltraSound: CL=GF1 IRQ, CH=MIDI IRQ
  50. │                                                 DX=BASE ADDRESS
  51. │        -> Returns AX=driver version if successful, else 0.
  52. │       Note: If the driver was initialized correctly, it HAS TO BE CLOSED
  53. │             at program end using subfunction #1.
  54. └
  55. ┌──CLOSE DRIVER────────────────────────────────────────────────────────────────
  56. │       BX=1
  57. │           Close driver, stop playing, put soundcard in a safe state,
  58. │           restore all interrupt vectors etc.
  59. └
  60. ┌──LOAD MODULE─────────────────────────────────────────────────────────────────
  61. │       BX=2, DS:DX=filename
  62. │           Stop any sound output and load modulefile stored in ds:dx, which
  63. │           has to end with a zero byte. Does not start playing the song.
  64. │       -> Returns AX=number of channels (4,6,8) if successful, else zero.
  65. └
  66.  
  67. ┌──START MODULE────────────────────────────────────────────────────────────────
  68. │       BX=3
  69. │           Start playing previously loaded song.
  70. └
  71. ┌──STOP MODULE─────────────────────────────────────────────────────────────────
  72. │       BX=4
  73. │           Stop any sound output at once.
  74. └
  75. ┌──MAIN VOLUME─────────────────────────────────────────────────────────────────
  76. │       BX=5, AL=volume
  77. │           Change mainvolume. Valid values are between 0 (lowest) and
  78. │           64 (loudest).
  79. └
  80. ┌──STATUS──────────────────────────────────────────────────────────────────────
  81. │       BX=6
  82. │           Get driver's playing status
  83. │        -> Returns AX=1 if sound is being played, else zero.
  84. └
  85. ┌──GET POSITION────────────────────────────────────────────────────────────────
  86. │       BX=7, AL=0
  87. │           Get playing position (to syncronize graphic effects).
  88. │        -> Returns AH=PatternNumber, AL=LineNumber (AX=0 if not playing).
  89. └
  90. ┌──SET POSITION────────────────────────────────────────────────────────────────
  91. │       BX=7, AL<>0
  92. │           Set playing position. Value in AL is added to current players
  93. │           pattern position. You cannot step below first and past last
  94. │           pattern. Reasonable values are 1 or -1 (0FFh).
  95. └
  96. ┌──PEAKS───────────────────────────────────────────────────────────────────────
  97. │       BX=8, ES:DI=peak buffer
  98. │           Copy the volume settings of each channel to peak buffer, which
  99. │           has to hold a maximum of 8 bytes. The number of channels is
  100. │           known after successful load of modulefile (subfunction #2).
  101. └──────────────────────────────────────────────────────────────────────────────
  102.  
  103.  
  104.          All registers will contain the same value after a subfunction
  105.         call, except AX, which will contain anything different from
  106.         zero if the call was successful.
  107.  
  108.          Using this conventions you can link the drivers in any
  109.         programming language, that supports inline assembly
  110.         instructions.
  111.  
  112.          TASM users can have things a little bit easier, if using the
  113.         library MODPLAY.LIB. You just have to add the statement
  114.  
  115.             INCLUDE MODPLAY.INC
  116.  
  117.          into your asm source and the drivers plus a fully automatic
  118.         hardware detection are linked. This gives you two new procs
  119.         called
  120.  
  121.             Mod_Driver      : general far call address to drivers
  122.             Mod_End_Seg     : far proc that returns last segment in ax
  123.  
  124.          The big advantage of this library is that you do not have to
  125.         load drivers into memory. You call Mod_Driver as shown above,
  126.         only the first function is altered slightly containing now the
  127.         option to choose which driver to use:
  128.  
  129.  
  130. ┌──SELECT AND INIT DRIVER──────────────────────────────────────────────────────
  131. │       BX=0, AX=sounddevice (CX,DX=configuration)
  132. │           Initialize driver selected by register AX. If AX=0 a detection
  133. │           will decide which driver to use, and then try to inizialize it.
  134. │           This should work in most cases. But you have the opportunity to
  135. │           bypass the detection, and manually select and setup the driver.
  136. │           In this case
  137. │              AX=1 stands for SoundBlaster driver
  138. │              AX=2   "     "  SoundBlaster Pro driver
  139. │              AX=3   "     "  Gravis UltraSound driver
  140. │           and CX,DX must hold the configuration as required by the common
  141. │           function #0.
  142. │        -> Returns AX=driver version if successfull, else zero.
  143. └
  144.          The second proc called Mod_End_Seg returns in register AX the
  145.         last segment address of the player to which you can adjust the
  146.         main program's memory control block. The new initialisation
  147.         copies the selected driver to the lowest possible memory
  148.         location (over the first driver) to avoid wasting ram.
  149.  
  150. ┌──GET DRIVER END ADDRESS──────────────────────────────────────────────────────
  151. │        -> Returns AX=driver end segment (unused)
  152. │      Note: Only call this proc after initialisation!
  153. └
  154.          There is also an example file available to illustrate you the
  155.         use of this library. It is coded in very, very easy assembler.
  156.         Of course I do know segment instructions, but this wouldn't
  157.         make the source more readable.
  158.  
  159.  
  160.                                                Lord Excess in Dezember '95
  161. 
  162.